<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="en-US">
<head>
  <title>yGuard 2.0 - Ant Java Bytecode Obfuscator and Shrinker - Documentation</title>
  <!--<link rel="stylesheet" href="ystyle.css" type="text/css">-->

  <style type="text/css">

    /*
     * CSS1 stylesheet for DocBook-generated yFiles Developer's Guide.
     */

    a {
      color: #AA5522;
      font-weight: bold;
    }
    a:link,
    a:visited {
      text-decoration: none;
    }
    a:active,
    a:focus,
    a:hover {
      text-decoration: underline;
    }

    ul ul a {
      color: #AA5522;
      font-weight: normal;
    }

    pre.programlisting,
    pre.screen {
      background: #E8E8E8;
      border: 2px solid #C8C8C8;
      padding-left: 4px;
      padding-right: 4px;
      padding-top: 4px;
      padding-bottom: 4px;
      font-size: 12px;
      margin-top: 2px;
    }

    tt.code {
      color: #0000C0;
      font-family: "Courier New", Courier, monospace;
    }

    tt.classname {
      color: #B000B0;
      font-weight: bold;
    }

    body.book {
    }

    h1,
    h4,
    h5,
    h6 {
      font-family: sans-serif;
    }

    p {
      padding-bottom: 0px;
      padding-top: 0px;
      margin-top: 8px;
      margin-bottom: 0px;
    }

    h2 {
      font-size: 120%;
      color: #4079EA;
      margin-top: 8px;
      margin-bottom: 0px;
    }

    h3 {
      font-size: 110%;
      margin-top: 8px;
      margin-bottom: 0px;
    }

    body {
      font-family: Verdana, sans-serif;
      font-size: 12px;
      background-color: #FFFFFF;
      margin-left: 12px;
      margin-right: 12px;
      margin-top: 12px;
      margin-bottom: 12px;
      color: #000000;
      text-align: justify;
    }

    div.navheader {
      background-color: #A4B9EA;
      border-bottom-style: solid;
      border-bottom-width: 1px;
      padding-left: 10px;
      padding-right: 10px;
      margin-left: -12px;
      margin-right: -12px;
      margin-top: -12px;
    }
    div.navheader hr {
      color: #A4B9EA;
      border: none;
      height: 0px;
    }
    div.navfooter {
      background-color: #A4B9EA;
      border-top-style: solid;
      border-top-width: 1px;
      padding-left: 10px;
      padding-right: 10px;
      margin-left: -12px;
      margin-right: -12px;
      margin-bottom: -12px;
    }
    div.navfooter hr {
      color: #A4B9EA;
      border: none;
      height: 0px;
    }

    div.bibliography,
    div.colophon,
    div.glossary,
    div.index,
    div.part,
    div.preface,
    div.refentry,
    div.reference {
      margin-left: 10px;
      margin-right: 10px;
    }

    div.index div.index {
      margin-left: 0px;
      margin-right: 0px;
    }

    div.appendix,
    div.book,
    div.chapter,
    div.legalnotice {
    }

    div.highlights {
      background: #F8F8F8;
      border: 2px solid #C8C8C8;
      padding-left: 4px;
      padding-right: 4px;
    }

    div.apiexcerpt,
    div.example,
    div.figure,
    div.striped,
    div.table {
      padding-top: 4px;
      padding-bottom: 0px;
    }

    div.striped table,
    div.table table {
      border-collapse: collapse;
      border: 1px solid white;
      vertical-align: baseline;
      font-size: 100%;
      margin-top: 1px;
    }
    div.striped table thead th,
    div.table table thead th {
      background-color: #A4B9EA;
      border: 1px solid white;
      color: #000000;
    }
    /*
    div.striped table tbody tr.evenrow, div.table table tbody td {
    */
    div.striped table tbody tr.evenrow td {
      vertical-align: baseline;
      border: 1px solid white;
    }
    div.striped table tbody tr.evenrow td,
    div.table table tbody td {
    /*
      background-color: #D3DAEA;
    */
      background-color: #E3EEFE;
      vertical-align: baseline;
      color: #000000;
      border: 1px solid white;
    }

    td div.mediaobject {
      background-color: #FFFFFF;
    }

    div.figure div.informaltable td {
      font-size: 10px;
      padding-left: 1px;
      padding-right: 1px;
      text-align: center;
    }

    table.copyright {
      font-size: 90%;
      font-style: italic;
      text-align: right;
      margin-top: 20px;
    }

    span.java_lineComment {
      color: #005000;
    }
    span.java_blockComment {
      color: #005000;
    }
    span.java_stringLiteral {
      color: #99006B;
    }
    span.java_numericLiteral {
      color: #780000;
    }
    span.java_keyword {
      color: #000099;
      font-weight: bold;
    }
    span.java_methodCall {
      color: black;
      font-weight: bold;
    }


  </style>



  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
  <meta http-equiv="content-language" content="en">
  <meta http-equiv="language" content="en">
  <meta http-equiv="reply-to" content="yguard@yWorks.com">
  <meta name="audience" content="all">
  <meta name="classification" content="software">
  <meta name="copyright" content="Copyright &copy; 2002-2006 yWorks. All Rights Reserved.">
  <meta name="distribution" content="global">
  <meta name="publisher" content="yWorks, http://www.yWorks.com">
  <meta name="rating" content="Safe For Kids">
</head>

<body>
<p>
  This document explains how to use the yGuard Java obfuscation and shrinking software together with Ant. yGuard
  is a product of <a href="http://www.yworks.com/">yWorks GmbH</a>, creator of
  the outstanding Java<sup><font size="-2">TM</font></sup> graph visualization framework
  <a href="http://www.yworks.com/products/yfiles">yFiles</a> and other fine
  <a href="http://www.yworks.com/products/">products</a>.
</p>
<p>
  Documentation for the deprecated Ant syntax of previous yGuard releases is still <a href="yguard_ant_howto_old.html">available</a>.
</p>

<h1>yGuard 2.0 Ant Task Documentation</h1>

<h2>Contents</h2>

<div class="standardtext">
  <ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#installation">Installation</a></li>
    <li><a href="#hints">General Hints &amp Troubleshooting</a></li>
    <li><a href="#dtd">DTD used for Ant <code>&lt;yguard></code></a></li>

    <li><a href="#yguard">The <code>yguard</code> Element</a></li>
    <li><a href="#inoutpair">The <code>inoutpair</code> Elements</a></li>
    <li><a href="#externalclasses">The <code>externalclasses</code> Element</a></li>
    <li><a href="#attribute">The <code>attribute</code> Elements</a></li>
    <li><a href="#shrink">The <code>shrink</code> Element</a></li>
    <li><a href="#entrypointjar">The <code>entrypointjar</code> Element</a></li>
    <li><a href="#rename">The <code>rename</code> Element</a></li>

    <li><a href="#property">The <code>property</code> Elements</a></li>
    <li><a href="#keep">The <code>keep</code> Element</a></li>
    <li><a href="#class">The <code>class</code> Elements</a></li>
    <li><a href="#method">The <code>method</code> Elements</a></li>
    <li><a href="#field">The <code>field</code> Elements</a></li>
    <li><a href="#sourcefile">The <code>sourcefile</code> Elements</a></li>
    <li><a href="#linenumbertable">The <code>linenumbertable</code> Elements</a></li>

    <li><a href="#adjust">The <code>adjust</code> Elements</a></li>
    <li><a href="#map">The <code>map</code> Element</a></li>
    <li><a href="#patch">Generating Patch Jars</a></li>
    <li><a href="#examples">Complete Examples</a></li>
      <ul>
        <li><a href="#ex:build">Example 1: Getting started with ANT and yGuard</a></li>
        <li><a href="#ex:api">Example 2: A Public API</a></li>
        <li><a href="#ex:demo">Example 3: A Demo Program</a></li>
        <li><a href="#ex:externalclasses">Example 4: A Program Using an External Library</a></li>
        <li><a href="#ex:adjust">Example 5: A Program with .properties Files and Other Resource Files</a></li>
        <li><a href="#ex:attribute">Example 6: A Program Linked Against a Library That Needs to be Obfuscated</a></li>
        <li><a href="#ex:extends">Example 7: Using the extends and implements attributes (Serializable exclusion)</a></li>
      </ul>
    <li><a href="#deobfuscation">Deobfuscating Stacktraces Etc.</a></li>
    <li><a href="#problems">Problems and Bug Reports</a></li>
  </ul>
</div>

<a name="introduction"></a>

<h1>Introduction</h1>

<div class="standardtext">
  <p>
    Using the yGuard Ant task, name obfuscation and code shrinking can be seamlessly integrated into your deployment
    process.<br/>
    The <a href="#yguard"><code>yguard</code></a> task contains two nested elements that perform the name obfuscation
    and code shrinking separately:
    <ul>
      <li>The <a href="#shrink"><code>shrink</code></a> element removes all code elements that are not reachable from
        the entrypoints given in the nested <a href="#keep"><code>keep</code></a> element.</li>
      <li>The <a href="#rename"><code>rename</code></a> element performs name-obfuscation, renaming all packages,
        classes, methods and fields according to a selectable name-mapping scheme.<br/>
        Elements can be excluded from the renaming process using a nested <a href="#keep"><code>keep</code></a> element.
      </li>
    </ul>

    Both elements operate on the same set of input and output files
    specified in the containing <a href="#yguard"><code>yguard</code></a> element.
  </p>
</div>

<a name="installation"></a>

<h1>Installation</h1>

<div class="standardtext"><p>
  In order to make use of yGuard's <code>yguard</code> task you must have Ant properly installed and configured
  to run it. After <a href="http://www.yworks.com/en/products_yguard_about.htm#downloads">downloading</a>
  and extracting the jar file
  (<code>yguard.jar</code>), place it in a path near to your build script. You may use
  absolute paths, but in the following example, we expect the jar file to lie
  in the same directory as your build file.
</p>

  <p>
    In order the get the Ant task running you should insert a couple of lines in
    your build script (<code>build.xml</code>):
  </p>

  <!--
  <pre class="programlisting">
    &lt;taskdef name="yguard"
      classname="com.yworks.yguard.ant.YGuardTask"
      classpath="yguard.jar"/>

    &lt;target name="yguard">
      &lt;yguard>
        &lt;!-- insert your yguard elements here
      &lt;/yguard>
    &lt;/target>
  </pre>

  <p>
    Alternatively, you can place the <code>taskdef</code> element inside the
    target that uses the yguard task:
  </p>

  -->

  <pre class="programlisting">
    &lt;target name="yguard">
      &lt;taskdef name="yguard"
      classname="com.yworks.yguard.YGuardTask"
      classpath="yguard.jar"/>
      &lt;yguard>
        &lt;!-- insert your yguard elements here -->
      &lt;/yguard>
    &lt;/target></pre>
  <a name="dtd"></a>
</div>

<p>
  For a complete <code>build.xml</code> file have a look at the
  <a href="#ex:build">examples section</a>.
</p>

<a name="hints"></a>

<h1>General Hints &amp; Troubleshooting</h1>

<div class="standardtext">
  <p>
    There are a couple of things you should be aware of when obfuscating and shrinking
    software.<br/>
    The weakest part of an application considering name obfuscation and code shrinking is code that uses
    reflection to dynamically load classes, invoke methods etc. Therefore, you have to be especially careful
    when using the <code>yguard</code> task on applications that rely on reflection.

    <!--You can find a lot of information on
    <a href="http://www.retrologic.com">http://www.Retrologic.com</a>. This is
    the site which hosts 'Retroguard'. The yGuard <i>library</i> has been derived from Retroguard.
    -->
    <br/>
    The most important facts to keep in mind when using yGuard are described here briefly:
  </p>
  <ul>
    <li>If you use the <code>rename</code> task, code in the form of <code>MyApplication.class</code> will break
      if MyApplication will be obfuscated by name
      and the obfuscation switch <a href="#replaceclassnamestrings"><code>replaceClassNameStrings</code></a> is set to
      <code>false</code>.
      The <code>shrink</code> task will currently recognize code in the form of <code>MyApplication.class</code> only if
      the java files
      were compiled using an arbitrary version of the standard javac compiler (although the shrinking engine might
      recognize the <code>.class</code> construct also if the classes were compiled using a compiler that generates
      similar bytecode).
    </li>
    <li>Automatic introspection and reflection will break in most cases, when
      you decide to obfuscate the corresponding methods and fields. If you use the <code>shrink</code> task and your
      application uses
      reflection you should explicitly designate all entities loaded per reflection as code entrypoints using the <a
            href="#keep"><code>keep</code></a> element.
      <br/>
      If your application is broken after using the <code>shrink</code> task, consider using the <a href="#createstubs">
      <code>createStubs</code></a> attribute of the <code>shrink</code> task to find out which additional entities you
      need to include in the <a href="#keep"><code>keep</code></a> element.
    </li>
    <li><code>Class.forName(className)</code> will not work when using the <code>rename</code> task unless you use the
      obfuscated name string in your variable or the String is a local constant and
      <a href="#replaceclassnamestrings"><code>replaceClassNameStrings</code></a> is not set or set to <code>true</code>
      .
      If you use the <code>shrink</code> task, <code>className</code> should be contained in the list of entrypoints
      using
      the <a href="#keep"><code>keep</code></a> element.
    <li>The customized serialization mechanism will not work if you
      obfuscated or shrinked the writeObject and readObject methods as well as the serializationUID field.
    </li>
    <li>Simple bean introspection will not work, if you decide to
      obfuscate your public accessor methods, since it makes use of
      reflection.
    </li>
    <li>
      If you do not set the <code>-Xmx</code> property for the Java virtual machine, the <code>yguard</code> Ant task
      might fail due to a <code>java.lang.OutOfMemoryError</code>.<br />
      To solve this problem, set the <code>-Xmx</code> option in the <code>ANT_OPTS</code> variable, e.g.:
      <pre class="programlisting">bash> export ANT_OPTS="-Xmx512M"
or
cshell> setenv ANT_OPTS "-Xmx512M"</pre>
    </li>
  </ul>
</div>

<h1>DTD used for Ant <code>&lt;yguard></code></h1>

<div class="standardtext">
<p>
  The obfuscation and shrinking process can be completely configured inside your Ant script.
  The <code>yguard</code> task and nested elements should be used according to the following DTD (please note that this
  is for information purposes only,
  i.e. you do not have to include the following lines anywhere):
</p>

<pre class="programlisting">
  &lt;!ELEMENT yguard (inoutpair+,externalclasses?,attribute*,(shrink|rename)+)>

  &lt;!ELEMENT inoutpair EMPTY>
  &lt;!ATTLIST inoutpair
  in CDATA #REQUIRED
  out CDATA #REQUIRED>

  &lt;!ELEMENT externalclasses ANY>
  &lt;!-- the externalclasses element is used just like Ant's classpath
  element. See the Ant documentation for further details-->

  &lt;!ELEMENT attribute (patternset)*>

  &lt;!ELEMENT shrink (entrypointjar*,keep?)>

  &lt;!ELEMENT rename (property*,patch?,adjust*,map?,keep?)>

  &lt;!ELEMENT property EMPTY>
  &lt;!ATTLIST property
  name CDATA #REQUIRED
  value CDATA #REQUIRED>

  &lt;!ELEMENT patch (class)*>

  &lt;!ELEMENT adjust (#PCDATA)>
  &lt;!ATTLIST adjust
  replaceName CDATA #REQUIRED
  replaceContent CDATA #REQUIRED
  replacePath CDATA #REQUIRED>

  &lt;!ELEMENT map (class|method|field|package)*>

  &lt;!ELEMENT package (#PCDATA)>
  &lt;!ATTLIST package
  name CDATA #REQUIRED
  map CDATA #REQUIRED>

  &lt;!ELEMENT keep (class|method|field|sourcefile|linenumbertable)*>
  &lt;!--
  NOTE: the nested &lt;sourcefile>,&lt;linenumbertable> and &lt;attribute> sections are only
  supported in the &lt;rename> element.
  -->
  &lt;!ATTLIST keep
  linenumbertable CDATA #IMPLIED
  localvariabletable CDATA #IMPLIED
  localvariabletypetable CDATA #IMPLIED
  runtimeinvisibleannotations CDATA #IMPLIED
  runtimeinvisibletypeannotations CDATA #IMPLIED
  runtimevisibleannotations CDATA #IMPLIED
  runtimevisibletypeannotations CDATA #IMPLIED
  sourcefile CDATA #IMPLIED>

  &lt;!ELEMENT class (patternset)*>
  &lt;!ATTLIST class
  classes CDATA #IMPLIED
  fields CDATA #IMPLIED
  map CDATA #IMPLIED
  methods CDATA #IMPLIED
  name CDATA #IMPLIED>
  &lt;!--
  NOTE: the map attribute is only supported
  if the &lt;class> element is nested inside an &lt;rename> element.
  -->

  &lt;!ELEMENT method (patternset)*>
  &lt;!ATTLIST method
  class CDATA #IMPLIED
  map CDATA #IMPLIED
  name CDATA #IMPLIED>
  &lt;!--
  NOTE: the map attribute is only supported
  if the &lt;method> element is nested inside an &lt;rename> element.
  -->

  &lt;!ELEMENT field (patternset)*>
  &lt;!ATTLIST field
  class CDATA #IMPLIED
  map CDATA #IMPLIED
  name CDATA #IMPLIED>
  &lt;!--
  NOTE: the field attribute is only supported
  if the &lt;method> element is nested inside an &lt;rename> element.
  -->
</pre>


<p>
  <b>Attention</b> users of IDEs that "support" the creation of Ant files (e.g. IDEA's IntelliJ):
  Your IDE may indicate some errors inside your ANT file when you use yGuard specific
  elements. This is because the IDE does not know about the DTD used by yGuard. However
  this is not a real problem, since the Ant file should nevertheless work as expected.
</p>


</div>


<a name="yguard"></a>

<h1>The <code>yguard</code> Element</h1>

<div class="standardtext">
<p>
  The <code>yguard</code> task contains elements that define basic properties common to the nested
  <a href="#rename"><code>rename</code></a> and <a href="#shrink"><code>shrink</code></a> tasks.<br/>
  Please see the <a href="#hints">General Gints &amp; Troubleshooting</a> section to learn about
  common pitfalls when using name obfuscation and shrinking software.

</p>


<p class="title"><b>Attributes</b></p>
  The <code>yguard</code> element has no attributes.

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><a href="#inoutpair"><code>inoutpair</code></a></li>
      <li><a href="#externalclasses"><code>externalclasses</code></a></li>
      <li><a href="#attribute"><code>attribute</code></a></li>
      <li><a href="#rename"><code>rename</code></a></li>
      <li><a href="#shrink"><code>shrink</code></a></li>
    </ul>
  </p>
</div>


<a name="inoutpair"></a>

<h1>The <code>inoutpair</code> Elements</h1>

<div class="standardtext">
<p>
  At least one <code>inoutpair</code> element has to be specified in order
  to run the yguard task. This elements specifies the paths to the input and output jar files.
</p>

<p>
  <div class="table"><p class="title"><b>Attributes</b></p>
    <table border="1" cellpadding="2" cellspacing="0">
      <thead><tr>
        <th width="12%" valign="top"><b>Attribute</b></th>
        <th width="78%" valign="top"><b>Description</b></th>
        <th width="10%" valign="top"><b>Required</b></th>
      </tr></thead>
      <tr>

        <td valign="top"><code>in</code></td>
        <td valign="top">specifies an exisiting jar file, which
          contains the unshrinked and unobfuscated .class files.</td>
        <td align="center" valign="top">Yes</td>

      </tr>

      <tr>

        <td valign="top"><code>out</code></td>
        <td valign="top">specifies a path to a jar file which
          will be created and used to put the results of the shrinking and obfuscation process.</td>
        <td align="center" valign="top">Yes</td>

      </tr>

      <tr>

        <td valign="top"><code>resources</code></td>
        <td valign="top">
          Will only be considered if the <a href="#yguard"><code>yguard</code></a> element contains a
          nested <a href="#shrink"><code>shrink</code></a> element.<br>
          Determines how the shrinking engine handles all non-.class files.<br>
          Currently the following three resource policies are supported:
          <ul>
            <li><code>copy</code>: the default, simply copies all resource files to the output jar.</li>
            <li><code>auto</code>: copies only those resource files that reside in a directory that still contains
              one or more .class files after shrinking.</li>
            <li><code>none</code>: discards all resource files.</li>
          </ul>

        </td>
        <td align="center" valign="top">No, defaults to <code>copy</code>.</td>

      </tr>

    </table>


    <p>
      <p class="title"><b>Child Elements</b></p>
      The <code>inoutpair</code> element has no child elements.
    </p>

  </div>
</p>

<a name="externalclasses"></a>

<h1>The <code>externalclasses</code> Element</h1>

<div class="standardtext">
  <p>
    If the jar to be processed by yGuard depends on external classes or libraries, this
    element can be used to specify classpaths to these entities.
    These libraries will neither be shrinked nor obfuscated. Use the
    <code>inoutpair</code> element for this purpose!
    See <a href="#ex:externalclasses">example 4</a> later in this document for an example of when to use this
    element.<br/>
    In order to achieve a maximum shrinking effect by the <code>shrink</code> task, all external dependencies should be
    declared in the <code>externalclasses</code> element. Otherwise, all non-private methods of classes
    that inherit from unresolvable classes will not be shrinked.
  </p>

  <p>
    The elements attributes and child elements can be seen on the <a
          href="http://ant.apache.org/manual/using.html#path">Ant documentation
    page about using path elements</a>.
  </p>
</div>


<a name="attribute"></a>

<h1>The <code>attribute</code> Element</h1>

<div class="standardtext">
  <p>
    Using the <code>attribute</code> element, you can specify which attributes present in the input
    classes should be kept in the obfuscated output classes.<br/>
    See <a href="#ex:attribute">example 6</a> later in this document for an example of when to use this
    element.<br/>
  </p>

  <p>
    <div class="table"><p class="title"><b>Attributes</b></p>
      <table border="1" cellpadding="2" cellspacing="0">
        <thead><tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="78%" valign="top"><b>Description</b></th>
          <th width="10%" valign="top"><b>Required</b></th>
        </tr></thead>
        <tr>

          <td valign="top"><code>name</code></td>
          <td valign="top">A comma-separated list of attribute names that are to be retained in the shrinked and/or
            obfuscated class
            files.</td>
          <td align="center" valign="top">Yes</td>

        </tr>

      </table>
    </div>
  </p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><a href="http://ant.apache.org/manual/CoreTypes/patternset.html"><code>patternset</code></a></li>
    </ul>
  </p>

  <p>
    An example:
  </p>
  <pre class="programlisting">
    &lt;attribute name="SourceFile, LineNumberTable, LocalVariableTable">
      &lt;patternset>
        &lt;include name="com.mycompany.mylibrary.**"/>
      &lt;/patternset>
    &lt;/attribute></pre>

  <p>
    This will retain the attributes named "<code>SourceFile</code>", "<code>LineNumberTable</code>",
    and "<code>LocalVariableTable</code>" effectively enabling debugging information for all classes in the
    <code>com.mycompany.mylibaray</code> package and subpackages.
  </p>
</div>

<a name="shrink"></a>

<h1>The <code>shrink</code> Element</h1>

<div class="standardtext">
  <p>
    The <code>shrink</code> task removes all classes, fields and methods that are not reachable from
    a number of entrypoints given by a nested <a href="#keep"><code>keep</code></a> element.<br />
    See the <a href="#examples">Complete Examples</a> section for explanation of some common use cases.
    If your code uses reflection, please read the <a href="#hints">General Hints &amp Troubleshooting</a>
    section for information on this topic.
  </p>

  <p>
    <div class="table"><p class="title"><b>Attributes</b></p>
      <table border="1" cellpadding="2" cellspacing="0">
        <thead><tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="78%" valign="top"><b>Description</b></th>
          <th width="10%" valign="top"><b>Required</b></th>
        </tr></thead>

        <tr>

          <td valign="top"><code>logfile</code></td>
          <td valign="top">Determines the name of the logfile that is generated
            during the shrinking process. The logfile contains information about the
            entrypoints the shrinking engine uses, the removed classes, methods and fields
            as well as any warnings.
            <br>
            If the name ends with a ".gz", yGuard will automatically create a gzipped version
            of the file which potentially saves a lot of disc space.</td>
          <td align="center" valign="top">No, defaults to <i>yshrinklog.xml</i></td>

        </tr>

        <tr>

          <td valign="top"><a name="createstubs"></a><code>createStubs</code></td>
          <td valign="top">

            Instead of removing methods completely, this attribute causes the <code>shrink</code> task to insert a
            method
            stub that throws a <code>java.lang.InternalError</code> if it is called. This attribute is very useful if
            the
            shrinking
            process causes your application to break and you are uncertain about which additional code entities you have
            to include in the <a href="#keep"><code>keep</code></a> element. <br/>
            Note that classes considered as completely obsolete by the shrinking engine are still removed completely -
            this attribute only
            affects obsolete methods of non-obsolete classes.


          </td>
          <td align="center" valign="top">No, defaults to <i>false</i></td>

        </tr>
      </table>
    </div>
  </p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><a href="#keep"><code>keep</code></a></li>
      <li><a href="#entrypointjar"><code>entrypointjar</code></a></li>
    </ul>
  </p>
</div>


<a name="entrypointjar"></a>

<h1>The <code>entrypointjar</code> Element</h1>

<div class="standardtext">
  <p>
    The <code>entrypointjar</code> element can be used for convenience if your application uses
    libraries that are to be shrinked, but the jarfile using these libraries should be left untouched by the shrinking
    engine.
    Such a jarfile could be specified as an <code>entrypointjar</code>.<br/>


  </p>

  <p>
    <div class="table"><p class="title"><b>Attributes</b></p>
      <table border="1" cellpadding="2" cellspacing="0">
        <thead><tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="78%" valign="top"><b>Description</b></th>
          <th width="10%" valign="top"><b>Required</b></th>
        </tr></thead>

        <tr>

          <td valign="top"><code>name</code></td>
          <td valign="top">Path to to the jar file to use as entrypointjar.
          <td align="center" valign="top">Yes</td>

        </tr>
      </table>
    </div>
  </p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    The <code>entrypointjar</code> element has no child elements.
  </p>

  <p>
    <p class="title"><b>Example</b></p>
    <pre class="programlisting">
      &lt;yguard>
        &lt;inoutpair in="lib-in.jar" out="lib-out.jar" />
        &lt;shrink>
          &lt;entrypointjar name="myApp.jar"/>
        &lt;/shrink>
      &lt;/yguard></pre>
  </p>
</div>

<a name="rename"></a>

<h1>The <code>rename</code> Element</h1>

<div class="standardtext">
  <p>
    The basic idea is, that all elements will be renamed by this task.
    Using the nested <a href="#keep"><code>keep</code></a> element, you have to specify all classes, methods, fields,
    and attributes that should be excluded from name obfuscation,
    i.e. that will <b>not</b> be renamed but kept in the API. There are different use cases, where you
    sometimes want to exclude or simply just have to exclude some elements from name obfuscation.
    See the <a href="#examples">Complete Examples</a> section for explanation of some common use cases.
    If your code uses reflection, please read the <a href="#hints">General Hints &amp Troubleshooting</a>
    section for information on this topic.
    Excluding elements can be achieved by using both
    the <a href="#keep"><code>keep</code></a> element and the <code>mainclass</code> attribute of the <code>
    rename</code> element.
  </p>

  <p>
    <div class="table"><p class="title"><b>Attributes</b></p>
      <table border="1" cellpadding="2" cellspacing="0">
        <thead><tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="78%" valign="top"><b>Description</b></th>
          <th width="10%" valign="top"><b>Required</b></th>
        </tr></thead>
        <tr>

          <td valign="top"><code>mainclass</code></td>
          <td valign="top">Can be used as a shortcut to specify the mainclass
            of your application. Both the class name and the main method will be excluded from
            name obfuscation. Alternatively you may want to consider to exclude the main method only. If your jar
            contains
            a <code>Main-Class</code> attribute, the rename task will automatically adjust the value to the obfuscated
            name.
          </td>
          <td align="center" valign="top">No</td>

        </tr>
        <tr>

          <td valign="top"><code>logfile</code></td>
          <td valign="top">Determines the name of the logfile that is generated
            during the renaming process. The logfile contains information about the
            mappings the name obfuscator generates as well as any warnings.
            <br>
            If the name ends with a ".gz", yGuard will automatically create a gzipped version
            of the file which potentially saves a lot of disc space.</td>
          <td align="center" valign="top">No, defaults to <i>yguardlog.xml</i></td>

        </tr>
        <tr>

          <td valign="top"><code>conservemanifest</code></td>
          <td valign="top">a boolean attribute (valid values: <code>true</code>/<code>false</code>) that determines
            whether
            the manifest file of the jars should be left untouched
            by the renaming engine. If set to <code>false</code>, the manifest
            will be modified to reflect the new message digests.</td>
          <td align="center" valign="top">No, defaults to <i>false</i>.</td>

        </tr>
        <tr>

          <td valign="top"><a name="replaceclassnamestrings"></a><code>replaceClassNameStrings</code></td>
          <td valign="top">a boolean attribute (valid values: <code>true</code>/<code>false</code>)
            that determines whether the renaming engine should try to replace hardcoded Strings, which
            are used in conjunction with the <code>MyClass.class</code> construct.
            If set to <code>false</code>, those Strings will be left
            untouched and code of the form <code>MyClass.class</code> will break if
            MyClass gets obfuscated by name. If set to <code>true</code> (the default), yGuard will try
            to workaround this problem by replacing the hardcoded String with the
            appropriate obfuscated name. However this will only work if the unobfuscated
            class file has been generated with the usual compilers ('javac', 'jikes' and
            'bjc') or compilers, that produce similar bytecode. This can also have the
            side-effect of modifying too many Strings, e.g if you have code that looks like
            <code>System.out.println("com.mycompany.MyClass");</code>, it might get
            replaced, if <code>MyClass.class</code> resides in the very same class with
            something like <code>System.out.println("com.A.OoO");</code>. It will most
            likely fail if the class has been previously obfuscated by another obfuscation
            tool or a different compiler has been used for compilation. Anyway it is
            always worth it to give it a try, if you want to have 'full obfuscation'.</td>
          <td align="center" valign="top">No, defaults to <i>true</i></td>

        </tr>
      </table>
    </div>
  </p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><a href="#keep"><code>keep</code></a></li>
      <li><a href="#property"><code>property</code></a></li>
      <li><a href="#patch"><code>patch</code></a></li>
      <li><a href="#adjust"><code>adjust</code></a></li>
      <li><a href="#map"><code>map</code></a></li>
    </ul>
  </p>
</div>


<a name="property"></a>

<h1>The <code>property</code> Elements</h1>

<div class="standardtext">
  <p>
    <code>property</code> elements can be used to give hints to the name obfuscation
    engine. Depending on the exact version of yGuard, the task may use these hints
    to control the process of obfuscation.
  </p>

  <p>

  <div class="table"><p class="title"><b>Attributes</b></p>
    <table border="1" cellpadding="2" cellspacing="0">
      <thead>
        <tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="78%" valign="top"><b>Description</b></th>
          <th width="10%" valign="top"><b>Required</b></th>
        </tr>
      </thead><tbody>
      <tr>

        <td valign="top"><code>name</code></td>
        <td valign="top">specifies a key which may be interpreted
          by the obfuscation task.</td>
        <td align="center" valign="top">Yes</td>

      </tr>
      <tr>

        <td valign="top"><code>value</code></td>
        <td valign="top">specifies the corresponding value of the
          property.</td>
        <td align="center" valign="top">Yes</td>

      </tr>
    </tbody>
    </table>
  </div>
</p>


<p>
<div class="table">
<p class="title"><b>The following properties are supported:</b></p>

<table border="1" cellpadding="2" cellspacing="0">
  <thead>
    <tr>
      <th width="12%" valign="top"><b>Name</b></th>
      <th width="88%" valign="top"><b>Description</b></th>
    </tr>
  </thead><tbody>
  <tr>
    <td valign="top"><code>error-checking</code></td>
    <td valign="top">can be used to tell yGuard
      to bail out if it detects any problems. Currently this property can
      be set to the following value:
      <ul>
        <li>
          <code>pedantic</code> will make the obfuscation run fail, i.e. the
          target which uses the <code>rename</code> element will fail, if
          yGuard detects any problems.
        </li>
      </ul></td>
  </tr>

  <tr>
    <td valign="top"><code>naming-scheme</code></td>
    <td valign="top">Can be used to tell the renaming engine to use
      a different naming scheme during the obfuscation. Currently this property can
      be set to one of the following values:
      <ul>
        <li>
          <code>small</code>Will produce very short names, i.e. the resulting jar
          file will be as small as possible.
        </li>
        <li>
          <code>best</code>Will produce names, that are very likely to be
          misunderstood by decompilers and disassemblers. Using this naming-scheme
          it is even impossible on most filesystems to successfully unjar or unzip the
          resulting jar file (Windows, Standard Unix, Standard Linux, MacOS).
          However this scheme takes up a lot of space and the resulting jar is likely to
          become large (typically roughly double the size).
        </li>
        <li>
          <code>mix</code>Is a mixture of both the other two values, which leads
          to reasonable small but still hard to decompile jar files.
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td valign="top"><code>language-conformity</code></td>
    <td valign="top">Can be used to advise
      the renaming engine to produce names, that should be decompilable by most decompilers. On
      the other hand, yGuard can produce class files that should be executable and
      verifiable by all of todays virtual machines, but produces absolutely nonsense
      names when decompiled (Ever tried to compile '<code>int class = false.this
      super(String$super.init if);</code>' ?!)
      Currently this property can
      be set to one of the following values:
      <ul>
        <li>
          <code>compatible</code>Will produce names, that are ok for (most) decompilers,
          java, jar and manifest files and can be unzipped to most filesystems.
        </li>
        <li>
          <code>legal</code>Will produce names, that are ok for (some) decompilers,
          java, jar and manifest files.
        </li>
        <li>
          <code>illegal</code>Will produce names, that will crash some tools but
          usually <b>not</b> the jvm, but JBuilder7 in many occasions for example.
        </li>
      </ul>
    </td>
  </tr>

  <tr>
    <td valign="top"><code>obfuscation-prefix</code></td>
    <td valign="top">Can be used to instruct the renaming engine
      to prefix packages, that are fully obfuscated with a given package prefix, e.g.
      <code>com.mycompany.obf</code>.
    </td>
  </tr>

  <tr>
    <td valign="top"><code>expose-attributes</code></td>
    <td valign="top">Can be used to give yGuard
      a list of attributes yGuard should expose in addition to the standard attributes.
      By default yGuard removes unneeded attributes like "Deprecated" from methods. The value
      can be a comma separated list of attributes as defined in
      <a href="http://java.sun.com/docs/books/vmspec/2nd-edition/html/ClassFile.doc.html#43817">
        Section 4.7 of the VM Specification of the .class File Format</a>. E.g. in order to keep
      the "Deprecated" attribute one can add the following property:
      <br>
      <code>&lt;property name="expose-attributes" value="Deprecated"/></code>
      <br>
      Note that this affects all classes which will be obfuscated. For a better control of which attributes should
      be exposed in what classes use the <a href="#attribute">Attribute Element</a>.
    </td>
  </tr>
</tbody>
</table>

</div>
</p>


<p>
  <p class="title"><b>Child Elements</b></p>
  The <code>property</code> element has no child elements.
</p>

</div>
<a name="keep"></a>

<h1>The <code>keep</code> Element</h1>

<div class="standardtext">
<p>
  This element is a child of the <a href="#rename"><code>rename</code></a> or <a href="#shrink"><code>shrink</code>
</a> element.
  It can be used to specify elements that are excluded from the parent <code>rename</code> or <code>shrink</code>
  task. The excluded classes, methods and fields are defined using nested <a href="#class"><code>class</code></a>,
  <a href="#method"><code>method</code></a> and <a href="#field"><code>field</code></a> elements.<br/>
  The elements given in the <code>keep</code> element are considered as code entrypoints.
  All code reachable from these entrypoints will be implicitly excluded from shrinking, too.
</p>

<p>
  <div class="table"><p class="title"><b>Attributes</b></p>

    <p>
      The <code>keep</code> element provides a number of boolean attributes that determine whether debug information
      and
      annotations present in the input class files are to be retained in the output files.
      The default behavior is to remove all of this information.  <br/>
      Note that a more fine-grained control over which attributes to keep for which class files is possible using the
      <a href="#attribute"><code>attribute</code></a> element.
    </p>

    <table border="1" cellpadding="2" cellspacing="0">
      <thead>
        <tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="68%" valign="top"><b>Description</b></th>
          <th width="20%" valign="top"><b>Required</b></th>
        </tr>
      </thead><tbody>
      <tr>
        <td valign="top"><code>sourcefile</code></td>
        <td valign="top">Determines whether the name of the original
          source code file should be included in the output class files.</td>
        <td align="center" valign="top">No, defaults to '<code>false</code>', i.e. this information will be removed.
        </td>
      </tr>
      <tr>
        <td valign="top"><code>linenumbertable</code></td>
        <td valign="top">Determines whether the line number table,
          that contains a mapping from each opcode in the class file to the line number
          in the original source code file
          should be included in the output class files.</td>
        <td align="center" valign="top">No, defaults to '<code>false</code>', i.e. this information will be removed.
        </td>
      </tr><tr>
      <td valign="top"><code>localvariabletable</code></td>
      <td valign="top">Determines whether the local variable table,
        that contains a mapping from each local variable in the class file
        to the name that has been used
        in the original source code file
        should be included in the output class files.</td>
      <td align="center" valign="top">No, defaults to '<code>false</code>', i.e. this information will be removed.</td>
    </tr>
      <tr>
        <td valign="top"><code>localvariabletypetable</code></td>
        <td valign="top">Determines whether the local variable type table,
          that contains a mapping from each local variable in the class file
          to the name and its generic type signature that has been used
          in the original source code file
          should be included in the output class files.</td>
        <td align="center" valign="top">No, defaults to '<code>false</code>', i.e. this information will be removed.
        </td>
      </tr>
      <tr>
        <td valign="top"><code>runtimevisibleannotations</code></td>
        <td valign="top">Determines whether annotations with the retention policy <code>RetentionPolicy.RUNTIME</code>
          should be included in the output class files.</td>
        <td align="center" valign="top">No, defaults to '<code>false</code>', i.e. these annotations will be removed.
        </td>
      </tr>
      <tr>
        <td valign="top"><code>runtimevisibleparameterannotations</code></td>
        <td valign="top">Determines whether method paramater annotations with the retention policy <code>
          RetentionPolicy.RUNTIME</code> should be included in the output class files.</td>
        <td align="center" valign="top">No, defaults to '<code>false</code>', i.e. these annotations will be removed.
        </td>
      </tr>
      <tr>
        <td valign="top"><code>runtimeinvisibleannotations</code></td>
        <td valign="top">Determines whether annotations with the retention policy <code>RetentionPolicy.CLASS</code>
          should be included in the output class files.</td>
        <td align="center" valign="top">No, defaults to '<code>false</code>', i.e. these annotations will be removed.
        </td>
      </tr>
      <tr>
        <td valign="top"><code>runtimeinvisibleparameterannotations</code></td>
        <td valign="top">Determines whether method paramater annotations with the retention policy <code>
          RetentionPolicy.CLASS</code> should be included in the output class files.</td>
        <td align="center" valign="top">No, defaults to '<code>false</code>', i.e. these annotations will be removed.
        </td>
      </tr>
    </tbody>
    </table>
  </div>
</p>


<p>
  <p class="title"><b>Common Child Elements</b></p>
  <ul>
    <li><a href="#class"><code>class</code></a></li>
    <li><a href="#method"><code>method</code></a></li>
    <li><a href="#field"><code>field</code></a></li>
  </ul>
</p>

<p>
  <p class="title"><b>Child Elements only available in the <a href="#rename"><code>rename</code></a> task</b></p>

  <p>
    The <a href="#rename"><code>rename</code></a> task allows for a special treatment of the
    <code>linenumbertable</code> and <code>sourcefile</code> attributes. This treatment can be
    specified in the following child elements:
  </p>
  <ul>
    <li><a href="#sourcefile"><code>sourcefile</code></a></li>
    <li><a href="#linenumbertable"><code>linenumbertable</code></a></li>
  </ul>
</p>

</div>
<a name="class"></a>

<h1>The <code>class</code> Element</h1>

<div class="standardtext">

<p>
  The <code>class</code> element can be used for excluding certain classes and/or their fields and methods
  from the renaming or shrinking process.<br/>
  If no <code>name</code>, <code>extends</code> or <code>implements</code> attribute is given and the <code>class</code>
  element contains no nested <code>patternset</code>, a <code>class</code>
  element matches all class names.
</p>

<p>
  The <code>classes</code>, <code>methods</code> and <code>fields</code> attributes
  tell the shrinking and renaming engines which classes, methods and fields to keep based on their visibility.
  The following table lists the possible values for all of these
  attributes and shows which elements will be excluded. A '*' denotes, that
  elements that have the given visibility will be excluded for the specified
  attribute value. A '-' denotes that the these elements will not be excluded from the process.
</p>
<br>

<div class="table">
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td><b>Value/Visibility</b></td>
      <td><code>public</code></td>
      <td><code>protected</code></td>
      <td><code>friendly</code></td>
      <td><code>private</code></td>

    </tr>
    <tr>
      <td><code>none</code></td>
      <td align="center">-</td>
      <td align="center">-</td>
      <td align="center">-</td>
      <td align="center">-</td>

    </tr>
    <tr>
      <td><code>public</code></td>
      <td align="center">*</td>
      <td align="center">-</td>
      <td align="center">-</td>
      <td align="center">-</td>

    </tr>
    <tr>
      <td><code>protected</code></td>
      <td align="center">*</td>
      <td align="center">*</td>
      <td align="center">-</td>
      <td align="center">-</td>

    </tr>
    <tr>
      <td><code>friendly</code></td>
      <td align="center">*</td>
      <td align="center">*</td>
      <td align="center">*</td>
      <td align="center">-</td>

    </tr>
    <tr>
      <td><code>private</code></td>
      <td align="center">*</td>
      <td align="center">*</td>
      <td align="center">*</td>
      <td align="center">*</td>

    </tr>
  </table>
</div>

<div class="table">
  <div class="table"><p class="title"><b>Attributes</b></p>

    <table border="1" width="100%">
      <thead valign="top">
        <tr>
          <th width="12%" valign="top">Attribute</th>
          <th width="78%" valign="top">Description</th>
          <th width="10%" valign="top">Required</th>
        </tr>
      </thead>
      <tbody>
        <tr>

          <td valign="top"><code>name</code></td>
          <td valign="top">The name of the class to be kept.</td>
          <td align="center" valign="top">No</td>

        </tr>
        <tr>

          <td valign="top"><code>classes</code></td>
          <td valign="top">The visibility of the classes to be kept.</td>
          <td align="center" valign="top">No, defaults to <code><b>none</b></code></td>

        </tr>
        <tr>

          <td valign="top"><code>methods</code></td>
          <td valign="top">The visibility of the methods to be kept.</td>
          <td align="center" valign="top">No, defaults to <code><b>none</b></code></td>

        </tr>

        <tr>

          <td valign="top"><code>fields</code></td>
          <td valign="top">The visibility of the fields to be kept.</td>
          <td align="center" valign="top">No, defaults to <code><b>none</b></code></td>

        </tr>

        <tr>

          <td valign="top"><a name="extends"></a><code>extends</code></td>
          <td valign="top">If no <code>name</code> attribute is given, keeps all classes that equal or extend the class
            defined by the given fully qualified classname. <br/>See <a href="#ex:extends">example 7</a> for an example
            usage of this attribute.</td>
          <td align="center" valign="top">No</td>

        </tr>

        <tr>

          <td valign="top"><a name="implements"></a><code>implements</code></td>
          <td valign="top">If no <code>name</code> attribute is given, keeps all classes that equal or implement the
            class defined by the given fully qualified classname.<br/>See <a href="#ex:extends">example 7</a> for an
            example
            usage of this attribute.</td>
          <td align="center" valign="top">No</td>

        </tr>
      </tbody>
    </table>
  </div>
</div>

<p>
  <p class="title"><b>Child Elements</b></p>
  <ul>
    <li><a href="http://ant.apache.org/manual/CoreTypes/patternset.html"><code>patternset</code></a></li>
  </ul>
</p>

<p class="title"><b>Explanation</b></p>

<p>
  There are three possible ways of specifying which classes will be excluded from the shrinking and obfuscation process:
</p>

<p>
<ol>
  <li>One can specify a single java class using the fully qualified name
    in java syntax with the <code>name</code> attribute. For example:
    <pre class="programlisting">&lt;class name="mypackage.MyClass"/></pre></li>
  <li>One can specify multiple java classes using a modified version of
    a patternset. The patternset's includes and excludes element should use
    java syntax, but the usual wildcards are allowed. Some examples:
    <pre class="programlisting">
      &lt;class>
        &lt;patternset>
          &lt;include name="com.mycompany.**.*Bean"/>
          &lt;exclude name="com.mycompany.secretpackage.*"/>
          &lt;exclude name="com.mycompany.myapp.SecretBean"/>
        &lt;/patternset>
      &lt;/class></pre>
    This will expose all classes which reside in the package subtree
    of com.mycompany and whose name ends with Bean except for those, that
    reside in the com.mycompany.secretpackage package and the single SecretBean
    in com.mycompany.myapp.
    <pre class="programlisting">
      &lt;class>
        &lt;patternset>
          &lt;include name="com.mycompany.myapp.MainClass"/>
          &lt;include name="org.w3c.sax?."/>
          &lt;exclude name="org.w3c.sax?.**.*$$*"/>
        &lt;/patternset>
      &lt;/class></pre>
    This will expose the MainClass class
    and all classes, which reside in packages like org.w3c.sax1, org.w3c.sax2, org.w3c.saxb
    except for inner classes. '$' is used as a separator between outer class names
    and inner class names. Since Ant uses '$' as an escape character, you have to
    use two consecutive '<code>$</code>'s ('<code>$$</code>') if you want to pass
    one as an argument to the task.
  </li>

  <li>
    Finally one can specify classes depending on their visibility, i.e. depending
    whether they have been declared <code>public</code>, <code>protected</code>, package friendly
    or <code>private</code> (inner classes). This can be achieved by
    additionally specifying the <code>classes</code> attribute in the <code>class</code> element.
    <pre class="programlisting">
      &lt;class classes="protected">
        &lt;patternset>
          &lt;include name="com.mycompany.myapi."/>
        &lt;/patternset>
      &lt;/class></pre>

    This will keep all class names, that are either <code>public</code> or
    <code>protected</code> and
    which reside in one of the subpackages of <code>com.mycompany.myapi</code>
    (note the
    abbreviation: the trailing dot behaves like the trailing '<code>/</code>' in the usual
    <code>patternset</code>, i.e. it could be rewritten as <code>com.mycompany.myapi.**.*</code>)
    <pre class="programlisting">
      &lt;class classes="protected"
        methods="protected"
        fields="protected">
        &lt;patternset>
          &lt;include name="**.*"/>
        &lt;/patternset>
      &lt;/class></pre>
    This example shows the very common use case of excluding a complete public API from the shrinking and obfuscation
    process.
    There is an abbreviation for this
    use case: you can omit the <code>patternset</code> element, since in the case where the
    <code>classes</code> attribute is specified and there is no
    <code>patternset</code> child
    element used, the task will automatically apply this rule. In this example
    all classes will be exposed, that are either public or protected.
    Their methods and fields will be exposed as long as they are declared
    <code>public</code> or <code>protected</code>. If a class is package friendly
    or <code>private</code> (inner classes), neither itself
    nor its methods or fields will be exposed.

    <p>

      The last example shows how to keep the public methods of certain classes only, but
      neither field names nor the class names themselves.

    <pre class="programlisting">
      &lt;class classes="none" methods="public" fields="none">
        &lt;patternset>
          &lt;include name="com.mycompany.myapi."/>
        &lt;/patternset>
      &lt;/class></pre>


  </li>

</ol>
</div>
<a name="method"></a>

<h1>The <code>method</code> Element</h1>

<div class="standardtext">
  <p>
    Using the <code>method</code> element you can specify methods by signature
    which should be excluded from shrinking or name obfuscation.
  </p>

  <p>
    <div class="table"><p class="title"><b>Attributes</b></p>
      <table border="1" cellpadding="2" cellspacing="0">
        <thead><tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="78%" valign="top"><b>Description</b></th>
          <th width="10%" valign="top"><b>Required</b></th>
        </tr></thead>

        <tr>

          <td valign="top"><code>name</code></td>
          <td valign="top">Specifies the method to keep. Use the
            complete signature using fully qualified class names and the return type!</td>
          <td align="center" valign="top">Yes</td>

        </tr>
        <tr>

          <td valign="top"><code>class</code></td>
          <td valign="top">Specifies the class which contains the
            method. Use the normal java syntax, i.e. the fully qualified name.
            This attribute can be omitted, if the patternset element is used as
            a child element, in which case all classes matching the patternset
            will be searched and their corresponding methods will be kept.</td>
          <td align="center" valign="top">No</td>

        </tr>

      </table>
    </div>
  </p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><a href="http://ant.apache.org/manual/CoreTypes/patternset.html"><code>patternset</code></a></li>
    </ul>
  </p>

  <p>
    <p class="title"><b>Examples</b></p>
  </p>
  <pre class="programlisting">
    &lt;method class="com.mycompany.myapp.MyClass"
      name="void main(java.lang.String[])"/>
    &lt;method class="com.mycompany.myapp.MyClass"
      name="int foo(double[][], java.lang.Object)"/>
    &lt;method name="void writeObject(java.io.ObjectOutputStream)">
      &lt;patternset>
        &lt;include name="com.mycompany.myapp.data.*"/>
      &lt;/patternset>
    &lt;/method>
    &lt;method name="void readObject(java.io.ObjectInputStream)">
      &lt;patternset>
        &lt;include name="com.mycompany.myapp.data.*"/>
      &lt;/patternset>
    &lt;/method></pre>

  <p>
    This will keep the main method of the MyClass class and the foo method.
    Additionally all readObject and writeObject methods (used for Serialization)
    will be kept in all classes of the com.mycompany.myapp.data package.
    Note that you have to specify the return argument's type, even if it is void
    and that you have to use the fully qualified name for all classes, even those,
    that are in the java.lang package.
  </p>
</div>
<a name="field"></a>

<h1>The <code>field</code> Element</h1>

<div class="standardtext">
  <p>
    Using the <code>field</code> element you can specify fields by name
    which should be excluded from shrinking or name obfuscation.
  </p>

  <p>
    <div class="table"><p class="title"><b>Attributes</b></p>
      <table border="1" cellpadding="2" cellspacing="0">
        <thead><tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="78%" valign="top"><b>Description</b></th>
          <th width="10%" valign="top"><b>Required</b></th>
        </tr></thead>

        <tr>

          <td valign="top"><code>name</code></td>
          <td valign="top">specifies the field to keep. Use the name
            of the field only, do not include its type!</td>
          <td align="center" valign="top">Yes</td>

        </tr>
        <tr>

          <td valign="top"><code>class</code></td>
          <td valign="top">Specifies the class which contains the
            field. Use the normal java syntax, i.e. the fully qualified name.
            This attribute can be omitted, if the patternset element is used as
            a child element, in which case the all classes matching the patternset
            will be searched and their corresponding fields will be kept.</td>
          <td align="center" valign="top">No</td>

        </tr>

      </table>
    </div>
  </p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><a href="http://ant.apache.org/manual/CoreTypes/patternset.html"><code>patternset</code></a></li>
    </ul>
  </p>

  <p>
    <p class="title"><b>Examples</b></p>
  </p>
  <pre class="programlisting">
    &lt;field class="com.mycompany.myapp.MyClass" name="field"/>
    &lt;field name="serialVersionUID">
      &lt;patternset>
        &lt;include name="com.mycompany.myapp.data.*"/>
      &lt;/patternset>
    &lt;/field></pre>

  <p>
    This will keep the field named 'field' of the MyClass class.
    Additionally all the serialVersionUID fields (used for Serialization)
    will be kept in all classes of the com.mycompany.myapp.data package.
  </p>
</div>


<a name="sourcefile"></a>

<h1>The <code>sourcefile</code> Element</h1>

<div class="standardtext">

  <p>
    The <code>sourcefile</code> element allows for a special treatment of the sourceFile attribute by the <a
          href="#rename"><code>rename</code></a> element.<br/>
    Using nested <code>property</code> elements, the mapping of sourceFile elements in obfuscated class files can be
    adjusted.
  </p>

  <div class="table">
    <p class="title"><b>The following properties are supported:</b></p>

    <table border="1" cellpadding="2" cellspacing="0">
      <thead>
        <tr>
          <th width="12%" valign="top"><b>Name</b></th>
          <th width="88%" valign="top"><b>Description</b></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td valign="top"><code>mapping</code></td>
          <td valign="top">
            the value of this property determines the name all sourceFile attributes matched by the <code>
            sourcefile</code>
            element are mapped to.
          </td>
        </tr>
      </tbody>
    </table>

  </div>

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><code>property</code></li>
      <li><a href="http://ant.apache.org/manual/CoreTypes/patternset.html"><code>patternset</code></a></li>
    </ul>
  </p>

  <p>
    <p class="title"><b>Examples</b></p>
  </p>

  <!--

  <pre class="programlisting">
    &lt;sourcefile>
      &lt;patternset>
        &lt;include name="com.mycompany.myapp.**"/>
      &lt;/patternset>
    &lt;/sourcefile>
  </pre>

  <p>
    This will expose source file names of all the classes in the com.mycompany.myapp packages and subpackages.
    Note that this will prevent proper obfuscation, since the name of the source file is normally strongly coupled
    with the unobfuscated name of the class (e.g. "<code>MySecretAlgorithm.java</code>".
    The following example shows how to overcome this.
  </p>

  -->

  <pre class="programlisting">
    &lt;sourcefile>
      &lt;property name="mapping" value="y"/>
      &lt;patternset>
        &lt;include name="com.mycompany.myapp.**"/>
      &lt;/patternset>
    &lt;/sourcefile></pre>

  <p>
    This will map all of the source file attributes in the packages below <code>com.mycompany.myapp</code> to "<code>
    y</code>",
    which is small and generally a nice letter.
  </p>
</div>


<a name="linenumbertable"></a>

<h1>The <code>linenumbertable</code> Element</h1>

<div class="standardtext">

<p>
  The <code>linenumbertable</code> element allows for a special treatment of the linenumbertable attribute by the
  <a href="#rename"><code>rename</code></a>.<br/>
  Using nested <code>property</code> elements, the mapping of linenumbertable elements in obfuscated class files can
  be
  adjusted.
</p>

<div class="table">
  <p class="title"><b>The following properties are supported:</b></p>


  <table border="1" cellpadding="2" cellspacing="0">
    <thead>
      <tr>
        <th width="12%" valign="top"><b>Name</b></th>
        <th width="88%" valign="top"><b>Description</b></th>
      </tr>
    </thead><tbody>
    <tr>
      <td valign="top"><code>mapping-scheme</code></td>
      <td valign="top">
        can be used with the following two values:
        <ul>
          <li>
            <code>scramble</code>: this will use a non-trivial algorithm to scramble the line numbers in the existing
            file.
            The algorithm implemented uses for each class a different scrambling scheme. The optional <code>
            scrambling-salt</code>
            property can be used to provide an integer value that will be used to "salt" the algorithm's random seed for
            the
            scrambling.
            The size of the (uncompressed) .class file will not change using this mapping scheme.
          </li>
          <li>
            <code>squeeze</code>: this will use a simple algorithm that virtually puts all of a methods code into the
            first
            line of
            code of the method. It will appear as if each method had been written in a single line of code.
            The advantage of this scheme is drastically reduced size requirements and thus smaller .class files, while
            at
            the same time
            it will be possible to unambiguously determine the exact method from a stacktrace.
          </li>
        </ul>
      </td>
    </tr>
    <tr>
      <td valign="top"><code>scrambling-salt</code></td>
      <td valign="top">
        can be used in conjunction with <code>mapping-scheme</code> to provide an integer value that will be used to
        "salt" the algorithm's random seed for the
        scrambling.
      </td>
    </tr>
  </tbody>
  </table>

</div>

<p>
  <p class="title"><b>Child Elements</b></p>
  <ul>
    <li><code>property</code></li>
    <li><code>patternset</code></li>
  </ul>
</p>

<p>
  <p class="title"><b>Examples</b></p>
</p>
<pre class="programlisting">
  &lt;linenumbertable>
    &lt;patternset>
      &lt;include name="com.mycompany.myapp.**"/>
    &lt;/patternset>
  &lt;/linenumbertable></pre>

<p>
  This will keep the line numbers of all the classes in the com.mycompany.myapp packages and subpackages.
  Note that in order to see the line numbers in stacktraces, the <a href="#sourcefile"><code>sourcefile</code></a>
  attribute has to be retained for those files, too, since otherwise the JDK will display "<code>Unknown source.</code>
  "
  for the stack elements.
</p>
<pre class="programlisting">
  &lt;linenumbertable>
    &lt;property name="mapping-scheme" value="scramble"/>
    &lt;property name="scrambling-salt" value="1234"/>
    &lt;patternset id="CompanyPatternSet">
      &lt;include name="com.mycompany.myapp.**"/>
    &lt;/patternset>
  &lt;/linenumbertable>
  &lt;sourcefile>
    &lt;property name="mapping" value="y"/>
    &lt;patternset refid="CompanyPatternSet"/>
  &lt;/sourcefile></pre>

<p>
  This will keep scrambled line numbers for all classes found in and below the com.mycompany.myapp packages.
  The scrambling algorithm will use the given "salt" value to use a predefined scrambling scheme.
  In order to see the scrambled line numbers, a <a href="#sourcefile"><code>sourcefile</code></a> element is used
  on the same patternset, which is referenced by its previously declared reference id, to rename the source files to
  "<code>y</code>".
</p>
</div>


<a name="adjust"></a>

<h1>The <code>adjust</code> Element</h1>

<div class="standardtext">
  <p>
    Using the <code>adjust</code> element one can specify resource files whose names and/or
    contents should be adjusted by the rename engine to reflect the obfuscated class names.
    <br>
    <b>Note:</b>
    This will only adjust files that are part of the <code>inoutpair</code> jars!
    I.e. the fileset's root directory is the combined root of all jars that are passed to
    yGuard via the <code>inoutpair</code> elements. yGuard will not modify any of the files
    on disk, except for the out-jar!
  </p>

  <p>
    <div class="table"><p class="title"><b>Attributes</b></p>
      <table border="1" cellpadding="2" cellspacing="0">
        <thead><tr>
          <th width="12%" valign="top"><b>Attribute</b></th>
          <th width="78%" valign="top"><b>Description</b></th>
          <th width="10%" valign="top"><b>Required</b></th>
        </tr></thead>

        <tr>

          <td valign="top"><code>replaceName</code></td>
          <td valign="top">specifies whether or not the names of
            the specified resources should be adjusted.</td>
          <td align="center" valign="top">No, defaults to <code>false</code></td>

        </tr>
        <tr>

          <td valign="top"><code>replaceContent</code></td>
          <td valign="top">specifies whether or not the contents of
            resource files should be adjusted.</td>
          <td align="center" valign="top">No, defaults to <code>false</code></td>

        </tr>
        <tr>

          <td valign="top"><code>replacePath</code></td>
          <td valign="top">specifies whether or not the paths to the
            resource files should be adjusted.</td>
          <td align="center" valign="top">No, defaults to <code>true</code></td>

        </tr>
      </table>
    </div>
  </p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    The <code>adjust</code> element can be used just like the standard Ant
    <a href="http://ant.apache.org/manual/CoreTypes/zipfileset.html">ZipFileSet</a> element.
  </p>

  <p>
    Some examples:
  </p>
  <pre class="programlisting">
    &lt;!-- adjust the names of all java property files in the jars -->
    &lt;adjust replaceName="true">
      &lt;include name="**/*.properties"/>
    &lt;/adjust>

    &lt;!-- adjust the classnames specified within a single XML file in the jar -->
    &lt;adjust file="plugins.xml" replaceContent="true" />

    &lt;!-- suppress the adjustment of the resource path
    com/mycompany/myapp/resource in the jar. -->
    &lt;!-- the package <i>com.mycompany.myapp</i> still gets obfuscated. -->
    &lt;adjust replacePath="false">
      &lt;include name="com/mycompany/myapp/resource/*"/>
    &lt;/adjust></pre>

</div>
<a name="map"></a>

<h1>The <code>map</code> Element</h1>

<div class="standardtext">
  <p>The <code>map</code> element is an immediate optional child of the
    <a href="#rename"><code>rename</code></a> element. It can be used to specify the mapping
    for the renaming process directly. This is an advanced topic.</p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><code>package</code></li>
      <li><code>class</code></li>
      <li><code>method</code></li>
      <li><code>field</code></li>
    </ul>
  </p>

  <p>
    All of these elements use the <code>name</code> attribute to specify the specific
    element. The <code>method</code> and <code>field</code> element need the
    <code>class</code> attribute in order to function properly. Neither wildcards
    nor nested <code>patternset</code> elements are allowed.
    Use the <code>map</code> attribute to specify the new name (subpackage, classname,
    methodname and fieldname respectively). <br/>

    Some examples:
  </p>
  <pre class="programlisting">
    &lt;map>
      &lt;package name="com" map="etc"/>
      &lt;package name="com.mycompany" map="nocompany"/>
      &lt;package name="com.mycompany.myapp" map="asdf"/>
      &lt;class name="com.mycompany.myapp.MainApp" map="foo"/>
      &lt;method class="com.mycompany.myapp.MainApp"
        name="void main(java.lang.String[])" map="bar"/>
      &lt;field class="com.mycompany.myapp.MainApp" name="field" map="a"/>
    &lt;/map></pre>

  <p>

    In this example the package structure 'com.mycompany.myapp' will be obfuscated to
    'etc.nocompany.asdf'. The MainApp class will be called 'foo' and its main method
    will be remapped to 'bar' (and can therefor not be executed from commandline anymore).
    The field called 'field' will be renamed to 'a'.
  </p>
</div>
<a name="patch"></a>

<h1>Generating Patch Jars</h1>

<div class="standardtext">
  <p>
    The true power of the <code>map</code> element lies in its use together
    with the <code>patch</code> element, which itself is a child element
    of the <code>rename</code> top level element.
  </p>

  <p>
    <p class="title"><b>Attributes</b></p>
    The <code>yguard</code> element has no attributes.
  </p>

  <p>
    <p class="title"><b>Child Elements</b></p>
    <ul>
      <li><a href="#class"><code>class</code></a></li>
    </ul>
  </p>

  <p>
    Using the <code>patch</code> element one can generate jars, that can be used
    to serve as patches for versions of an application that have already been
    deployed in obfuscated form.
    During the main obfuscation run, yGuard produces an xml-logfile, in which
    the mapping between the unobfuscated and obfuscated names is contained.
    The <code>patch</code> element is used to declare a set of classes, that need
    to be patched. During the obfuscation, yGuard will include those files
    in the obfuscated jars only, that are declared inside this element.<br>
    For example:
  </p>
  <pre class="programlisting">
    &lt;patch>
      &lt;class name="com.mycompany.myapp.MainClass"/>
      &lt;class>
        &lt;patternset>
          &lt;include name="com.mycompany.myapp.bugs.*"/>
        &lt;/patternset>
      &lt;/class>
    &lt;/patch>
    &lt;map logfile="yguardlog.xml"/></pre>

  <p>
    This will only include the MainClass class and all classes that belong to the
    bugs package in a patch jar.
    In order to work with the previously delivered obfuscated version, it is
    important to use the <code>map</code> element to specify the mapping of the elements
    from the previous run. This can most conveniently be achieved by
    specifying the log file from the corresponding run in the map's logfile attribute.
  </p>
  <a name="examples"></a>
</div>

<h1>Complete Examples</h1>

<div class="standardtext">
<p>
  There will be some examples given, that represent common use cases.
</p>

<a name="ex:build"></a>

<h2>Example 1: Getting started with Ant and yGuard (for Ant newbies)</h2>

<p>
  Following are the contents of a complete <code>build.xml</code> file.
  Just copy the following lines to a new document named <code>build.xml</code>,
  put the file into your project's root directory and edit the file to suit your needs.
</p>

<pre class="programlisting">
  &lt;?xml version="1.0" encoding="UTF-8"?>
  &lt;!-- file build.xml in your project root directory -->
  &lt;!-- Ant build script for yfiles -->
  &lt;!-- The java based Ant tool is available from -->
  &lt;!-- http://jakarta.apache.org/ant -->
  &lt;!-- This file demonstrates the use of the yGuard byte -->
  &lt;!-- code obfuscator from yWorks Gmbh -->
  &lt;!-- yGuard can be downloaded from -->
  &lt;!--- http://www.yworks.com/products/yguard -->

  &lt;project name="project" default="yguard" basedir=".">

    &lt;!-- edit the following lines to your needs -->
    &lt;target name="init">
    &lt;property name="project_name" value="DemoProject"/>
    &lt;property name="srcDir" value="."/>
    &lt;property name="classDir" value="classes"/>
    &lt;property name="jar" value="${project_name}.jar"/>
    &lt;property name="obfjar" value="${project_name}_obf.jar"/>
    &lt;property name="renamelog" value="${project_name}_renamelog.xml"/>
    &lt;property name="shrinklog" value="${project_name}_shrinklog.xml"/>
    &lt;property name="mainclass" value="com.mycompany.myapp.Main"/>
    &lt;mkdir dir="${classDir}" />
    &lt;/target>


    &lt;target depends="jar" name="yguard">
      &lt;taskdef name="yguard" classname="com.yworks.yguard.YGuardTask"
      classpath="yguard.jar"/>
      &lt;!-- the following can be adjusted to your needs -->
      &lt;yguard>

        &lt;inoutpair in="${jar}" out="${obfjar}"/>

        &lt;shrink logfile="${shrinklog}">

          &lt;keep>
            &lt;class classes="protected"
            methods="protected" fields="protected">
              &lt;patternset>
                &lt;include name="com.mycompany.publicapi.**.*"/>
                &lt;exclude name="com.mycompany.publicapi.private.*"/>
                &lt;include name="com.mycompany.menu.reflection.**.*"/>
              &lt;/patternset>
            &lt;/class>
          &lt;/keep>
        &lt;/shrink>

        &lt;rename mainclass="${mainclass}" logfile="${renamelog}">
          &lt;property name="error-checking" value="pedantic"/>

          &lt;keep>
            &lt;class classes="protected"
            methods="protected" fields="protected">
              &lt;patternset>
                &lt;include name="com.mycompany.publicapi.**.*"/>
                &lt;exclude name="com.mycompany.publicapi.private.*"/>
              &lt;/patternset>
            &lt;/class>
          &lt;/keep>
        &lt;/rename>

      &lt;/yguard>

    &lt;/target>

    &lt;!-- compile -->
    &lt;target name="compile" depends="init">
      &lt;javac srcdir="${srcDir}" includes="com/mycompany/**/*.java"
        destdir="${classDir}">
      &lt;/javac>
    &lt;/target>

    &lt;!-- create .jar -->
    &lt;target name="jar" depends="compile">
      &lt;jar jarfile="${jar}"
        basedir="${classDir}"
        includes="com/mycompany/**">
        &lt;fileset dir="${srcDir}">
          &lt;include name="com/mycompany/resources/*.properties"/>
        &lt;/fileset>
      &lt;/jar>
    &lt;/target>

    &lt;!-- run project -->
    &lt;target name="run" depends="yguard">
      &lt;java classname="${mainclass}" fork="true">
      &lt;classpath>
        &lt;pathelement location="${obfjar}"/>
      &lt;/classpath>
      &lt;/java>
    &lt;/target>

    &lt;!-- removes all that has been built -->
    &lt;target name="clean" depends="init">
      &lt;delete dir="${classDir}" includeEmptyDirs="true" />
    &lt;/target>
  &lt;/project>

  &lt;!-- end file build.xml --></pre>

<h2>Example 2: A Public API</h2>

<p>
  An alternative <code>yguard</code> section could look like this:
</p>

<a name="ex:api"></a>

<pre class="programlisting">
  &lt;yguard>

    &lt;inoutpair in="classes.jar" out="classes_obf.jar"/>
    &lt;inoutpair in="utils.jar" out="utils_obf.jar"/>

    &lt;!-- don't let the obfuscator remove the "Deprecated" -->
    &lt;!-- attributes from the .class file entries -->
    &lt;attribute name="Deprecated"/>

    &lt;shrink
      logfile="shrinklog.xml">
      &lt;keep>
        &lt;class classes="protected"
        methods="protected"
        fields="protected"/>
      &lt;/keep>
    &lt;/shrink>

    &lt;rename mainclass="com.mycompany.myapp.Main"
      logfile="obflog.xml">
      &lt;keep>
        &lt;class classes="protected"
        methods="protected"
        fields="protected"/>
      &lt;/keep>
    &lt;/rename>

  &lt;/yguard></pre>

<p>
  This case is especially useful when you want to provide and expose a public API.
  All the classes, methods and fields, that can be seen in a javadoc generated
  API will be excluded from the shrinking and renaming tasks.
  Package friendly and private classes, methods and fields
  will be shrinked or obfuscated whenever possible.<br>
  This example also displays the use of the "attribute" element. In this
  case it prevents the yguard task from removing the "Deprecated" flag from
  the entities in the .class files.
</p>

<a name="ex:demo"></a>

<h2>Example 3: A Demo Program</h2>

<pre class="programlisting">
  &lt;yguard>

    &lt;inoutpair in="demo.jar" out="demo_obf.jar"/>

    &lt;shrink logfile="shrinklog.xml">

      &lt;keep>

        &lt;!-- main method -->
        &lt;method name="void main(String[])" class="com.mycompany.myapp.Main" />

        &lt;!-- needed for reflection -->
        &lt;class name="com.mycompany.myapp.data.DataObject"
        methods="public" fields="none"/>
        &lt;!-- needed for reflection (name only) -->
        &lt;class name="com.mycompany.myapp.data.InnerDataObject"/>
        &lt;!-- needed for serialization -->
        &lt;method name="void writeObject(java.io.ObjectOutputStream)">
          &lt;patternset id="datapatternset">
            &lt;include name="com.mycompany.myapp.data.*"/>
          &lt;/patternset>
        &lt;/method>
        &lt;method name="void readObject(java.io.ObjectInputStream)">
          &lt;patternset refid="datapatternset"/>
        &lt;/method>
        &lt;field name="serialVersionUID">
          &lt;patternset refid="datapatternset"/>
        &lt;/field>
      &lt;/keep>
    &lt;/shrink>

    &lt;rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">

      &lt;property name="language-conformity" value="illegal"/>
      &lt;property name="naming-scheme" value="mix"/>
      &lt;keep>
        &lt;class name="com.mycompany.myapp.data.DataObject"
        methods="public" fields="none"/>
        &lt;class name="com.mycompany.myapp.data.InnerDataObject"/>
        &lt;method name="void writeObject(java.io.ObjectOutputStream)">
          &lt;patternset refid="datapatternset" />
        &lt;/method>
        &lt;method name="void readObject(java.io.ObjectInputStream)">
          &lt;patternset refid="datapatternset"/>
        &lt;/method>
        &lt;field name="serialVersionUID">
          &lt;patternset refid="datapatternset"/>
        &lt;/field>
      &lt;/keep>
    &lt;/rename>

  &lt;/yguard></pre>

  <p>
    This example demonstrates the common use case of a demo program. The <code>keep</code> sections
    of both the <code>shrink</code> and <code>rename</code> elements contain code entities that will
    often have to be excluded from the shrinking and renaming process. These are the main code entrypoints (the main method),
    classes that are loaded per reflection and fields and methods needed for serialization. Note how the same
    patternsets can be reused using the <code>id</code> and <code>refid</code> attributes.
  </p>

<a name="ex:externalclasses"></a>

<h2>Example 4: A Program Using an External Library</h2>

<pre class="programlisting">

  &lt;yguard>

    &lt;inoutpair in="mydemo.jar" out="mydemo_obf.jar"/>

    &lt;externalclasses>
      &lt;pathelement location="lib/external.jar"/>
      &lt;pathelement location="lib/additional/classes/"/>
    &lt;/externalclasses>

    &lt;shrink logfile="shrinklog.xml">
      &lt;property name="error-checking" value="pedantic"/>
      &lt;keep>
        &lt;method name="void main(String[])" class="com.mycompany.myapp.Main" />
        &lt;class classes="public"/>
      &lt;/keep>
    &lt;/shrink>

    &lt;rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">
      &lt;property name="error-checking" value="pedantic"/>
      &lt;keep>
        &lt;class classes="public"/>
      &lt;/keep>
    &lt;/rename>

  &lt;/yguard></pre>

<p>
  This example demonstrates full method and field obfuscation for a program, that
  has external dependencies. The dependencies are specified in the
  <code>externalclasses</code> element using standard Ant path specification
  mechanisms. Classes residing in <code>lib/external.jar</code> and underneath
  the <code>lib/additional/classes/</code> directory (note the trailing slash),
  will be used to resolve external dependencies during the obfuscation run.
  This is necessary if external classes want to access obfuscated classes
  directly using an externally defined interface or superclass. yGuard
  automatically detects externally declared methods and prevents renaming and shrinking of
  these items. As a result, the shrinked and obfuscated jar file can be used together with
  unmodified versions of external libraries without causing any problems.
  <br>
  This example also demonstrates the use of the <code>error-checking</code>
  property. In this case the Ant target fails if any problem is detected during
  the obfuscation run.
</p>

<a name="ex:adjust"></a>

<h2>Example 5: A Program with <code>.properties</code> Files and Other Resource Files</h2>

<pre class="programlisting">

  &lt;yguard>

    &lt;inoutpair in="myapp.jar" out="myapp_obf.jar"/>

    &lt;shrink logfile="shrinklog.xml">
      &lt;keep>
        &lt;!-- single entrypoint: main method -->
        &lt;method name="void main(String[])" class="com.mycompany.myapp.Main" />
      &lt;/keep>
    &lt;/shrink>

    &lt;rename mainclass="com.mycompany.myapp.Main" logfile="renamelog.xml">

      &lt;adjust replaceContent="true">
        &lt;!-- plain-text class names in the config files will -->
        &lt;!-- be replaced with the obfuscated name versions -->
        &lt;include name="**/*.config"/>
        &lt;include name="com/mycompany/myapp/init/Main.properties"/>
      &lt;/adjust>
      &lt;adjust replacePath="false">
        &lt;!-- keep the complete path to the resources, (gifs...) even if -->
        &lt;!-- package com.mycompany.myapp gets obfuscated by name -->
        &lt;include name="com/mycompany/myapp/resources/*"/>
      &lt;/adjust>
      &lt;adjust replaceName="true">
        &lt;!-- Replace the .properties files' names with the obfuscated -->
        &lt;!-- versions if the corresponding .class files get obfuscated -->
        &lt;include name="**/*.properties"/>
        &lt;/adjust>
    &lt;/rename>

  &lt;/yguard></pre>

<p>
  This example, too, demonstrates full method and field obfuscation for a program, that
  uses .properties files and other resources files.
  Some configuration files are used that contain fully qualified classnames
  for plugins that are going to be obfuscated. Therefore yGuard is instructed to
  automatically replace the plain-text entries in those files with the obfuscated
  name versions.
  <br>
  Additionally some resources are hardcoded into the classes (image locations
  and html files, e.g.). yGuard gets instructed not to move these resource files
  even if they reside in a package structure that is obfuscated.
  <br>
  Since the property files have been created with the same name as the classes
  that make use of them and they are being loaded using <code>this.getClass().getName()</code>,
  yGuard is configured to rename the .properties files according to the obfuscated
  names of the corresponding .class files.
</p>


<a name="ex:attribute"></a>

<h2>Example 6: A Program Linked Against a Library That Needs to be Obfuscated</h2>

<pre class="programlisting">

  &lt;yguard>

    &lt;inoutpair in="myapp.jar" out="myapp_obf.jar"/>
    &lt;inoutpair in="lib/thirdpartylib.jar" out="lib/thirdpartylib_obf.jar"/>

    &lt;externalclasses>
      &lt;pathelement location="lib/external.jar"/>
    &lt;/externalclasses>

    &lt!-- Keep all of the attributes for debugging, e.g. -->
    &lt;attribute name="Deprecated, SourceFile, LineNumberTable, LocalVariableTable>
      &lt;patternset refid="myopenapp"/>
    &lt;/attribute>

    &lt;rename mainclass="org.myorg.myapp.Main" logfile="renamelog.xml">

      &lt;property name="error-checking" value="pedantic"/>

      &lt;keep>
      &lt!-- Tell the obfuscator to only adjust my classes -->
      &lt!-- to work with the obfuscated 3rd party library -->
      &lt!-- but leave them virtually unmodified otherwise -->
      &lt!-- The libconnector package however will be -->
      &lt!-- obfuscated as much as possible -->
      &lt;class classes="private" methods="private" fields="private">
        &lt;patternset id="myopenapp">
          &lt;include name="org.myorg.myapp.**"/>
          &lt;exclude name="org.myorg.myapp.mylibconnector.**"/>
        &lt;/patternset>
      &lt;/class>

      &lt;/keep>
    &lt;/rename>

  &lt;/yguard></pre>

<p>
  This example demonstrates almost no method, class, and field obfuscation for a program, that
  has external dependencies and additionally depends on a third party library jar
  which has to be obfuscated before deployment. Only those parts that actually interface with
  the third party jar in the <code>mylibconnector</code> package are being obfuscated.
  Nothing in the third party library jar will be
  exposed in the final application, everything will be obfuscated and the code
  in the open application that makes use of the third party jar will be adjusted.
  Note that the public part of the application will still be debuggable since all of the
  crucial attributes will be exposed for the open application part.
  <br>
  The dependencies are specified in the
  <code>externalclasses</code> element using standard Ant path specification
  mechanisms. Classes residing in <code>lib/external.jar</code>
  will be used to resolve external dependencies during the obfuscation run.
  This is not strictly necessary in this case since the public API will be fully exposed,
  i.e. no methods which have been declared by interfaces or super class in external
  classes will be renamed.
</p>

<a name="ex:extends"></a>

<h2>Example 7: Using the <code>extends</code> and <code>implements</code> attributes (Serializable exclusion)</h2>


<pre class="programlisting">

  &lt;yguard>

    &lt;inoutpair in="myapp.jar" out="myapp_obf.jar"/>

    &lt;shrink>
      &lt;keep>
        &lt;!-- main method -->
        &lt;method name="void main(java.lang.String[])" class="org.myorg.myapp.Main" />
        &lt;!-- serializable classes -->
        &lt;class implements="java.io.Serializable" classes="private" methods="private" fields="private" />
        &lt;!-- menu items loaded per reflection -->
        &lt;class extends="org.myorg.myapp.MyMenuItem" classes="friendly" methods="public" fields="public" />
      &lt;/keep>
    &lt;/shrink>

    &lt;rename mainclass="org.myorg.myapp.Main" logfile="renamelog.xml">

      &lt;keep>
        &lt;method name="void readObject(java.io.ObjectInputStream)" />
        &lt;method name="void writeObject(java.io.ObjectOutputStream)" />
        &lt;field name="serialVersionUID" />
        &lt;class extends="org.myorg.myapp.MyMenuItem" classes="friendly" methods="public" fields="public" />
      &lt;/keep>
    &lt;/rename>

  &lt;/yguard></pre>

<p>
  This example demonstrates the usage of the new <a href="#implements"><code>implements</code></a> and <a href="#extends"><code>extends</code></a> attributes of the
  <a href="#class"><code>class</code></a> element. All Serializable classes are excluded from shrinking by using the <a href="#implements"><code>implements</code></a>
  attribute
  of the <a href="#class"><code>class</code></a> element.
  Additionally, all classes that extend the base class for menu items, <code>org.myorg.myapp.MyMenuItem</code>, are
  defined as entrypoints
  for the shrinking engine using the <a href="#extends"><code>extends</code></a> attribute of the <a href="#class"><code>class</code></a> element.
  The <code>readObject</code> and <code>writeObject</code> methods and the field <code>serialVersionUID</code> needed
  for serialization are excluded from name obfuscation as well.
</p>


</div>

<a name="deobfuscation"></a>

<h1>Deobfuscating Stacktraces Etc.</h1>

<div class="standardtext">
  <p>
    yGuard provides a simple tool that makes it easy for the obfuscating party to deobfuscate stacktraces
    which have been obfuscated using yGuard. During the obfuscation yGuard produces an xml logfile which can
    automatically be gzipped for convenient storage. You should always keep those logfiles in order to
    be able to deobfuscate fully qualified classnames or methods or fields for debugging purposes e.g.
    <br>
    In order to run the yGuard deobfuscation tool do the following:
    <pre class="programlisting">
      Console> java -jar yguard.jar mylogfile.xml</pre>
    A tiny GUI will popup that will enable you to easily deobfuscate stacktraces and fully qualified classnames
    as well as provide a convenient way to browse the mapping generated by yGuard.
    <br>
    In the main window a tree view displays the package, class, and classmember hierarchy using the unobfuscated
    names. For each entry that has been obfuscated
    (classes, packages, methods, and fields that have not been obfuscated at all may not always be shown in the tree)
    the corresponding mapped/obfuscated name is displayed.
    <br>
    The two buttons at the top of the window allow to change the sorting of the items in the tree structure, so that
    they are either sorted according to their names before or after the obfuscation. Items will always be sorted by type
    first:
    packages, classes, innerclasses, methods, and fields. Small icons provide a convenient way to quickly find the
    corresponding items.
  </p>

  <p>
    The lower part of the window contains an editable text area that can be used to enter text or paste stacktraces in.
    Pressing the button at the bottom of the window labelled "Deobfuscate" will trigger the deobfuscation of the
    contents in
    the text area. The tool will try to identify fully qualified class names (separated by dots) and use the mapping
    information to reconstruct the original names. If the tool identifies a stack trace element, it will try to
    deobfuscate
    scrambled line numbers, too, if they have been scrambled during the obfuscation process.
  </p>
</div>


<a name="problems"></a>

<h1>Problems and Bug Reports</h1>

<div class="standardtext">
  <p>
    If you experience any problems or think you have found a bug feel free to send
    an email to <a href="mailto:yguard@yworks.com">yguard@yworks.com</a> but
    please make sure you have read the documentation thoroughly before. We will
    do our best and try to answer your questions.
  </p>
</div>

<hr size="1" style="color:#666666;background:none;margin-top:30px">
<a name="copyright"></a>
<div class="standardtext">
  <p style="font-style:italic;color:#666666;font-size:0.9em">
Copyright &copy; 2002-2006 yWorks. All Rights Reserved.
</p>
</div>
</body>
</html>
<!-- EOF -->
